Message dispatcher. More...

#include <kanzi/core/cpp/platform.hpp>
#include <kanzi/core/cpp/chrono.hpp>
#include <kanzi/core/metadata/metaclass.hpp>
#include <kanzi/core/message/message_type.hpp>
#include <kanzi/core.ui/message/message_arguments.hpp>
#include <kanzi/core/legacy/kzs_types.hpp>
#include <kanzi/core/legacy/debug/kzs_error.hpp>
#include <kanzi/core/cpp/memory.hpp>
#include "kzu_message_dispatcher_properties.h"

Classes
struct	kanzi::TimerMessageArguments

class	kanzi::MessageDispatcherProperties

class	kanzi::MessageDispatcherProperties::WriteLogMessageArguments

class	kanzi::MessageDispatcherProperties::TimerMessageArguments

Namespaces
	kanzi

Typedefs
typedef kzsError(*	KzuMessageHandlerFunction) (kanzi::MessageArguments message, void userData)
	Message callback prototype. More...

typedef kzsError(*	KzuMessageDispatchFunction) (const kanzi::MessageArguments message, void userData)
	Application message callback prototype. More...

typedef function< void(const TimerMessageArguments &)>	kanzi::TimerFunction

typedef shared_ptr< void >	kanzi::TimerSubscriptionToken

Enumerations
enum	KzuTimerMessageMode { KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT, KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH }
	Timer mode. More...

Functions
KANZI_API kzsError	kzuMessageDispatcherCreate (const struct KzcMemoryManager memoryManager, struct KzuMessageDispatcher *out_messageDispatcher)
	Create a message dispatcher. More...

KANZI_API kzsError	kzuMessageDispatcherDelete (struct KzuMessageDispatcher *messageDispatcher)
	Destroy a message dispatcher. More...

KANZI_API kzsError	kzuMessageDispatcherAddHandler (const struct KzuMessageDispatcher messageDispatcher, kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, kanzi::Node messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
	Adds a message handler. More...

KANZI_API kzsError	kzuMessageDispatcherAddTunnellingHandler (const struct KzuMessageDispatcher messageDispatcher, kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, kanzi::Node messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
	Adds a message handler for tunneling phase. More...

KANZI_API kzsError	kzuMessageDispatcherIsHandlerSubscriptionValid (const struct KzuMessageDispatcher messageDispatcher, const kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, KzuMessageHandlerFunction handlerFunction, const void userData, kzBool *out_valid)
	Checks if a handler subscription is valid. More...

KANZI_API kzsError	kzuMessageDispatcherRemoveHandler (const struct KzuMessageDispatcher messageDispatcher, const kanzi::Node subscriptionSiteNode, const struct KzuMessageType messageType, KzuMessageHandlerFunction handlerFunction, const void userData)
	Removes a message handler. More...

KANZI_API kzsError	kzuMessageDispatcherDispatchMessage (struct KzuMessageDispatcher messageDispatcher, kanzi::MessageArguments message, kanzi::Node *source)
	Dispatches a message. More...

KANZI_API kzsError	kzuMessageDispatcherDispatchQueuedMessages (struct KzuMessageDispatcher *messageDispatcher, kzUint elapsedTime=0)
	Dispatches queued messages. More...

KANZI_API kzsError	kzuMessageDispatcherNotifyObjectDeleted (const struct KzuMessageDispatcher messageDispatcher, const kanzi::Node objectNode)
	Notifies the message dispatcher that an object node is being destroyed. More...

KANZI_API kzsError	kzuMessageDispatcherAddTimerHandler (KzuMessageDispatcher messageDispatcher, kzUint interval, enum KzuTimerMessageMode mode, KzuMessageHandlerFunction handlerFunction, void userData)
	Registers a timer handler. More...

KANZI_API kzsError	kzuMessageDispatcherRemoveTimerHandler (KzuMessageDispatcher messageDispatcher, KzuMessageHandlerFunction handlerFunction, const void userData)
	Unregisters a timer handler. More...

KANZI_API kanzi::optional< kanzi::chrono::milliseconds >	kzuMessageDispatcherGetProposedSleepTime (const KzuMessageDispatcher *messageDispatcher)
	Gets the proposed sleep time from message dispatcher. More...

KANZI_API kzUint	kzuMessageDispatcherGetTime (const struct KzuMessageDispatcher *messageDispatcher)
	Returns current time of message dispatcher in milliseconds. More...

KANZI_API TimerSubscriptionToken	kanzi::addTimerHandler (KzuMessageDispatcher *messageDispatcher, chrono::milliseconds interval, KzuTimerMessageMode mode, TimerFunction callback)

KANZI_API void	kanzi::removeTimerHandler (KzuMessageDispatcher *messageDispatcher, TimerSubscriptionToken token)

Detailed Description

Message dispatcher.

Provides a system to exchange messages between different parts of an application. Messages can be used to notify of an event or request operations and data.

Typedef Documentation

typedef kzsError(* KzuMessageHandlerFunction) (kanzi::MessageArguments *message, void *userData)

Message callback prototype.

typedef kzsError(* KzuMessageDispatchFunction) (const kanzi::MessageArguments *message, void *userData)

Application message callback prototype.

Enumeration Type Documentation

enum KzuTimerMessageMode

Timer mode.

Enumerator

KZU_TIMER_MESSAGE_MODE_ONCE

Timer will be called once after the specified interval elapses.

Unsubscribe still needed.

KZU_TIMER_MESSAGE_MODE_REPEAT

Timer will be called repeatedly at specified intervals.

Timers in this mode should be disabled when the application update cycle is called infrequently, for example in low power situations, as this generates excessive number of messages.

KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH

Same as KZU_TIMER_MESSAGE_MODE_REPEAT, but the system dispatches only the last message when a timer has several pending messages.

Function Documentation

KANZI_API kzsError kzuMessageDispatcherCreate	(	const struct KzcMemoryManager *	memoryManager,
		struct KzuMessageDispatcher **	out_messageDispatcher
	)

Create a message dispatcher.

KANZI_API kzsError kzuMessageDispatcherDelete ( struct KzuMessageDispatcher * messageDispatcher )

Destroy a message dispatcher.

KANZI_API kzsError kzuMessageDispatcherAddHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		kanzi::Node *	messageSource,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Adds a message handler.

Parameters

messageDispatcher	The message dispatcher to use.
subscriptionSiteNode	Object node that is associated with the message subscription created by this function.
messageType	Type of the message to match.
messageSource	Source of the message (as returned by kzuMessageGetSource) to match.
handlerFunction	Function to call when a matching message appears.
userData	User data pointer passed to handlerFunction.

KANZI_API kzsError kzuMessageDispatcherAddTunnellingHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		kanzi::Node *	messageSource,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Adds a message handler for tunneling phase.

KANZI_API kzsError kzuMessageDispatcherIsHandlerSubscriptionValid	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData,
		kzBool *	out_valid
	)

Checks if a handler subscription is valid.

KANZI_API kzsError kzuMessageDispatcherRemoveHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const kanzi::Node *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData
	)

Removes a message handler.

KANZI_API kzsError kzuMessageDispatcherDispatchMessage	(	struct KzuMessageDispatcher *	messageDispatcher,
		kanzi::MessageArguments *	message,
		kanzi::Node *	source
	)

Dispatches a message.

The associated handlers are called immediately.

KANZI_API kzsError kzuMessageDispatcherDispatchQueuedMessages	(	struct KzuMessageDispatcher *	messageDispatcher,
		kzUint	elapsedTime = `0`
	)

Dispatches queued messages.

Generally should be called once per frame.

KANZI_API kzsError kzuMessageDispatcherNotifyObjectDeleted	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const kanzi::Node *	objectNode
	)

Notifies the message dispatcher that an object node is being destroyed.

This will cancel all messages where the specified node is the source of the message or the current site during routing.

KANZI_API kzsError kzuMessageDispatcherAddTimerHandler	(	KzuMessageDispatcher *	messageDispatcher,
		kzUint	interval,
		enum KzuTimerMessageMode	mode,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Registers a timer handler.

Parameters

messageDispatcher	The message dispatcher to use.
interval	timeout in milliseconds in case of a one-shot timer, and the interval in case of a repeating timer.
mode	KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT or KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH. KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH is recommended for a repeating timer because it calls handlerFunction only once when the interval has been exceeded several times over.
handlerFunction	The function to call when the timer expires.
userData	User data pointer passed to handlerFunction.

KANZI_API kzsError kzuMessageDispatcherRemoveTimerHandler	(	KzuMessageDispatcher *	messageDispatcher,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData
	)

Unregisters a timer handler.

KANZI_API kanzi::optional<kanzi::chrono::milliseconds> kzuMessageDispatcherGetProposedSleepTime ( const KzuMessageDispatcher * messageDispatcher )

Gets the proposed sleep time from message dispatcher.

This equals the smallest interval when a timer would be next executed. If no timers are present, returns an empty optional.

Parameters

messageDispatcher Message dispatcher to query.

Returns: Time until next timer handler should trigger (always nonnegative). Empty optional if no timer handlers present.

KANZI_API kzUint kzuMessageDispatcherGetTime ( const struct KzuMessageDispatcher * messageDispatcher )

Returns current time of message dispatcher in milliseconds.

Classes

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation